MPATROL

Section: mpatrol library (1)
Updated: 16 May 2000
Index Return to Main Contents

NAME

mpatrol - runs programs using the mpatrol library

SYNOPSIS

mpatrol [options] <command> [arguments]

DESCRIPTION

The mpatrol command is used to set various mpatrol library options when running command with its arguments. In most cases, command must have been linked with the mpatrol library, unless the -d option is used in which case command need only have been dynamically linked.

All mpatrol library diagnostics are sent to the file mpatrol.%n.log in the current directory by default (where %n is the current process id) but this can be changed using the -l option. Similarly, the default profiling output filename is mpatrol.%n.out. Note that the LOGALL option is always implicitly used for commands that are run by this command.

OPTIONS

All of the following options (except -d and -V) correspond to their listed mpatrol library option. See mpatrol(3) for more details on these options.

-1 <unsigned integer>: [SMALLBOUND] Specifies the limit in bytes up to which memory allocations should be classified as small allocations for profiling purposes.
-2 <unsigned integer>: [MEDIUMBOUND] Specifies the limit in bytes up to which memory allocations should be classified as medium allocations for profiling purposes.
-3 <unsigned integer>: [LARGEBOUND] Specifies the limit in bytes up to which memory allocations should be classified as large allocations for profiling purposes.
-A <unsigned integer>: [ALLOCSTOP] Specifies an allocation index at which to stop the program when it is being allocated.
-a <unsigned integer>: [ALLOCBYTE] Specifies an 8-bit byte pattern with which to prefill newly-allocated memory.
-C <unsigned range>: [CHECK] Specifies a range of allocation indices at which to check the integrity of free memory and overflow buffers.
-c: [CHECKALL] Specifies that all arguments to functions which allocate, reallocate and deallocate memory have rigorous checks performed on them.
-D <unsigned integer>: [DEFALIGN] Specifies the default alignment for general-purpose memory allocations, which must be a power of two.
-d: Specifies that programs which were not linked with the mpatrol library should also be traced, but only if they were dynamically linked. This option will only work if the system dynamic linker has the ability to preload a set of user-specified shared libraries via a special environment variable.
-e <string>: [PROGFILE] Specifies an alternative filename with which to locate the executable file containing the program's symbols.
-F <unsigned integer>: [FREESTOP] Specifies an allocation index at which to stop the program when it is being freed.
-f <unsigned integer>: [FREEBYTE] Specifies an 8-bit byte pattern with which to prefill newly-freed memory.
-G: [SAFESIGNALS] Instructs the library to save and replace certain signal handlers during the execution of library code and to restore them afterwards.
-g: [USEDEBUG] Specifies that any debugging information in the executable file should be used to obtain additional source-level information.
-L <unsigned integer>: [LIMIT] Specifies the limit in bytes at which all memory allocations should fail if the total allocated memory should increase beyond this.
-l <string>: [LOGFILE] Specifies an alternative file in which to place all diagnostics from the mpatrol library.
-M: [ALLOWOFLOW] Specifies that a warning rather than an error should be produced if any memory operation function overflows the boundaries of a memory allocation, and that the operation should still be performed.
-m: [USEMMAP] Specifies that the library should use mmap() instead of sbrk() to allocate system memory.
-N: [NOPROTECT] Specifies that the mpatrol library's internal data structures should not be made read-only after every memory allocation, reallocation or deallocation.
-n: [NOFREE] Specifies that the mpatrol library should keep all reallocated and freed memory allocations.
-O <unsigned integer>: [OFLOWSIZE] Specifies the size in bytes to use for all overflow buffers, which must be a power of two.
-o <unsigned integer>: [OFLOWBYTE] Specifies an 8-bit byte pattern with which to fill the overflow buffers of all memory allocations.
-P <string>: [PROFFILE] Specifies an alternative file in which to place all memory allocation profiling information from the mpatrol library.
-p: [PROF] Specifies that all memory allocations are to be profiled and sent to the profiling output file.
-Q <unsigned integer>: [AUTOSAVE] Specifies the frequency at which to periodically write the profiling data to the profiling output file.
-R <unsigned integer>: [REALLOCSTOP] Specifies an allocation index at which to stop the program when a memory allocation is being reallocated.
-S: [SHOWMAP & SHOWSYMBOLS] Specifies that a memory map of the entire heap and a summary of all of the function symbols read from the program's executable file should be displayed at the end of program execution.
-s: [SHOWFREED & SHOWUNFREED] Specifies that a summary of all of the freed and unfreed memory allocations should be displayed at the end of program execution.
-U <unsigned integer>: [UNFREEDABORT] Specifies the minimum number of unfreed allocations at which to abort the program just before program termination.
-V: Displays the version number of the mpatrol command.
-v: [PRESERVE] Specifies that any reallocated or freed memory allocations should preserve their original contents.
-w: [OFLOWWATCH] Specifies that watch point areas should be used for overflow buffers rather than filling with the overflow byte.
-X: [PAGEALLOC=UPPER] Specifies that each individual memory allocation should occupy at least one page of virtual memory and should be placed at the highest point within these pages.
-x: [PAGEALLOC=LOWER] Specifies that each individual memory allocation should occupy at least one page of virtual memory and should be placed at the lowest point within these pages.
-Z <unsigned integer>: [FAILSEED] Specifies the random number seed which will be used when determining which memory allocations will randomly fail.
-z <unsigned integer>: [FAILFREQ] Specifies the frequency at which all memory allocations will randomly fail.

AUTHOR

Graeme S. Roy <graeme@epc.co.uk>

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

This document was created by man2html, using the manual pages.
Time: 12:37:26 GMT, July 10, 2022